
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Diagnostics;

using Swaf;

namespace Swaf.DataAccess
{
	/// <summary>
	/// Provides support for manipulating a transaction beyond basic transaction voting
	/// provided through the ITransaction interface.
	/// </summary>
	/// <remarks>This interfaces defines a set of participants that should be used to
	/// control when a transaction is ultimately committed or rolled back based on the votes
	/// that have taken place (via the ITransaction interface).  Ultimately code 
	/// that is voting for a transaction's success or failure is also counted
	/// as a participant by doing a call to addParticipant to represent it. When the
	/// given code block is complete is should have a corresponding removeParticipant
	/// done for it.
	/// <p>This interface also defines a set of connections that are being
	/// managed within the transaction.  The set of these connections are what
	/// are actually committed or rolled back as voted on.</p></remarks>
	public interface ITransactionManager
	{
		IConnectionItem getConnection(string key);
		void addConnection(string key, IConnectionItem conn);
		
		/// <summary>
		/// The number of participants currently involved with the transaction.
		/// </summary>
		int Participants {get;}
		void addParticipant(object p);
		/// <summary>
		/// removes the given participant from the transaction.
		/// </summary>
		/// <remarks>When no more participants
		/// are involved, the transaction should ultimately be either committed or rolled
		/// back based on the votes on the transaction.  If rollback vote count is > 0 then
		/// all the connections in the transaction are rolled back, otherwise all the
		/// connections are committed.</remarks>
		/// <param name="p"></param>
		void removeParticipant(object p);
		/// <summary>
		/// When a participant votes to commit or rollback through the ITransaction
		/// interface, their vote is "tallied and remembed" such that it is possible
		/// to ask if a participant voted or not.  
		/// </summary>
		/// <param name="id">The identity of the participant as defined by the
		/// concrete implementation of this interface.</param>
		/// <returns></returns>
		bool hasIdentityVoted(object id);
	}
}